P R I N T   S H O P   C L I P   A R T

BY PHILIP LAMB  DIGITAL DYNAMICS

Essential Information
=====================

This program is freeware. Use it, enjoy it, and send no money!! You are asked to
distribute it as widely as possible, providing you retain it intact with all
necessary files, sourcecode and this documentation. You may not charge money for
the sale of this program, only for the cost of the distribution medium.

Requires Apple IIe or //c, with ramdisk, any size, called /RAM To begin using
simply place all the files from the Shrinkit archive into one directory, then
from Basic.System, run PS.CLIP.ART

Files included in this package
==============================

PS.CLIP.ART  This is the big cheese. It should be run from Basic.System to
start PS Clip Art

PS.CLIP.ART.PIC  This is the Digital Dynamics intro screen

CLIP.ART.CODE  Machine language subroutines used in PS.CLIP.ART

MG.UNPACK, UPK.OBJ  Minigraphic unpackers used by PS.CLIP.ART

AUX.TYPE.SET  A couple of little machine language utilities

PS.CLIP.ART.DOC  You have to know how to run it

CLIP.ART.CODE.S, MG.UNPACK.S, UPK.OBJ.S, AUX.TYPE.SET.S, UNPACK.FAST.S

The Merlin Pro source code for the machine language programs

UNPACK.FAST  Fast single-size unpacker, included for use in your own programs

Introduction
============

While this program is called "Print Shop Clip Art", you certainly do not need
Print Shop to run it! The great thing about this program is that it works with
something that you can easily create: Hires pictures. (Double Hires screens can
also be used. The program will read only the first half, thus some screens may
look odd.) It allows you to clip 88x52 black and white mini-graphics from hires
screens, assemble these graphics into clip art files, load these files into "The
Print Shop" or "The New Print Shop" by Br0derBund Software and print them in
cards, posters, calendars. Also included in the package, and most useful to
those without Print Shop are three mini graphic drawing programs. These can be
called from BASIC or assembly to display mini-graphics in 3 sizes anywhere on
the hires screen. This is great for use in programs where you need a
small-format graphic to appear.

The Minipix Format
==================

When the Print Shop first appeared, the only type of graphics it used were small
4 sector DOS3.3 files, called minipix. Because the range of them built into
Print Shop was limited, people drew their own, using the print Shop Graphic
Editor, and soon these little 88x52 pictures were everywhere. There were disks
and disks, just packed with them. The storage format was quite simple, basically
just a bit mapped image, with every 11 bytes of the file mapping to one line of
88 dots on the screen. An extra 4 filler bytes were tacked on the end of each
mini-graphic file. Each file held only 1 mini-graphic. 52 lines x 8 bytes + 4 =
576 bytes. Now when "The New Print Shop" came along, you could convert these
little graphics to the new format. It turns out that all that was done to each
graphic to convert it, was a small header was placed at the start, and the 4
filler bytes were dropped from the end, and so 576 byte graphics became 605 byte
"NPS" compatible graphics. (Other graphics formats exist for NPS but this
converted 605 byte kind is all that PS.CLIP.ART can use)

PS.CLIP.ART works with both of these formats. The converted 605 byte
mini-graphics are referred to as MINPICS, or as only one at a time can be
handled, MINIPIC. This is kept in a buffer in memory referred to as the minpic
buffer. Captures from the hires screen, redrawing onto the hires screen both use
this buffer. The old 576 byte graphics are referred to as CLIP ART FILES because
several of them can be assembled into a single file. A CLIP ART FILE with just
one graphic in it can be loaded into the (old) Print Shop if it is converted to
Dos3.3 using for example, Copy II Plus or Apple System utilities. Graphics can
be moved to and from this file from the MINPIC BUFFER.

For techies, the minipic buffer starts at 38400 or $9600 in memory. The 572
bytes of graphic data start at 38433 ($9621). The clip art file grows downwards
from 38400. There can be up to 24 mini-graphics in the file:

# GRAPHICS   LOAD @   FILE LENGTH    #     LOAD FILE @     FILE LENGTH
1     $93C0 (37824)   $240 (576)     13    $78C0 (30912)   $1D40 (7488)
2     $9180 (37248)   $480 (1152)    14    $7680 (30336)   $1F80 (8064)
3     $8F40 (36672)   $6C0 (1728)    15    $7440 (29760)   $21C0 (8640)
4     $8D00 (36096)   $900 (2304)    16    $7200 (29184)   $2400 (9126)
5     $8AC0 (35520)   $B40 (2880)    17    $6FC0 (28608)   $2640 (9792)
6     $8880 (34944)   $D80 (3456)    18    $6D80 (28032)   $2880 (10368)
7     $8640 (34368)   $FC0 (4032)    19    $6B40 (27456)   $2AC0 (10944)
8     $8400 (33792)   $1200 (4608)   20    $6900 (26880)   $2D00 (11520)
9     $81C0 (33216)   $1440 (5184)   21    $66C0 (26304)   $2F40 (12096)
10    $7F80 (32640)   $1680 (5760)   22    $6480 (25728)   $3180 (12672)
11    $7D40 (32064)   $18C0 (6336)   23    $6240 (25152)   $33C0 (13248)
12    $7B00 (31488)   $1B00 (6192)   24    $6000 (24576)   $3600 (13824)

The filler bytes of the first graphic in the file are utilised to record the
number of graphics in the file,and the file load address:
$95FD (38397) Number of graphics in file
$94FE & $95FF (L,H)Load address of file

Program organisation
====================

The program is split into 4 distinct areas, each of which is accessed from the
main menu.

The "EDIT MENU" deals with editing of the hires screen, clipping of graphics,
and drawing of graphics onto the hires screen. Initially, you are placed in the
hires screen viewing mode. Press the spacebar for a screen displaying the keys
that you can use.

The "MINIPIC MENU" deals with the minipic buffer, including saving as a New
Print Shop mini-graphic, loading a 605 byte converted mini-graphic, and viewing
the buffers contents. All operations are listed on the menu.

The "CLIP ART MENU" deals with the clip art file, including saving, loading,
clearing specific graphics within it to black, adding a graphic stored in the
minipic buffer to the file, moving a graphic in the file to the minipic buffer,
and viewing graphics in the minipic file. All operations are listed on the menu.

The "HIRES MENU" deals with hires screen loading, saving and clearing to black.
Note that to clear to white just clear to black and invert from the edit menu.
The options are listed on the menu.

Note that most operations are menu driven. Pressing escape or control-A from a
sub menu will return you to the main menu. If you have selected an option, but
you do not wish to carry it out, usually, pressing return without entering any
data will return you to the menu.

Typical operations
==================

Loading a screen, clipping a graphic, saving the graphic:
    
Go to the [H]ires menu. Use [P] prefix change and [/] catalog if you wish to
find the screen to load, then select [L]oad from the hires menu. Enter the
filename and press return. Note that double hires files may be loaded, but as
only the first half is read, the resulting hires creen may look slightly odd.
Get back to the main menu and press [E] to get to the edit screen. To clip a
graphic press [C]. A flashing capture box appears. Note that graphics can only
be clipped at one scale. The arrows and keys W,A,S,Z move 10 pixels at a time.
Keys I,J,K,M move 1 pixel at a time. To cancel capture mode press [escape] or to
do the capture press [return]. Note that the captured graphic is placed in the
minipic buffer, so any graphic in the buffer already will be wiped. When the
graphic capture is completed the screen will flash. Press [Q] to return to the
main menu. You can now select [M]inipic menu, to view the captured graphic.
[T]oggle scale selects the viewing scale. The graphic will be centred in the
screen. If the graphic capture is not satisfactory, you can go back to the edit
screen and try again. If it is OK, and you wish to save it as a 605 byte, single
graphic, NPS compatible file then choose the [S]ave option from the minipic
menu. If you wish to add it to the clip art file, or save it as an Old Print
Shop compatible graphic then follow the instructions below.

Creating a Clip-Art file, saving, loading:

A clip art file may be created by moving a graphic from the minipic buffer,
using the options under the [C]lip art menu. Graphics may also be moved to the
minipic buffer from the clip art file. To create a new clip art file, you should
first have the graphic to be added in the minipic buffer. Then from the clip art
menu select [M]ove, and following that [F]rom Minpic Buffer. If there are
currently graphics in the minipic file you will be given the option of
overwriting these. To just add to the end of the file, select [A] for append.
You may have up to 24 graphics in a clip art file. The moving to and from the
minipic file takes a minute, so be patient. Individual graphics can be viewed in
much the same way as for the buffer graphic. Simply set the viewing scale, and
select [V]iew from the menu. Graphics may be cleared by selecting [C] clear from
the menu. Clearing the last graphic in a file will shrink the file by 1. To
delete a graphic, and have those higher numbered move into its place is
possible, but requires some work. You must move each graphic that follows the
one to be deleted to the minipic buffer, and then move it from the minipic
buffer to its new place in the file, overwriting the graphic below. This must be
done for each graphic above the one to be deleted. Finally the last graphic in
the file should be cleared. When you are happy with the minipic file, selecting
[S]save will allow you to save it to disk. Clip art files can also be loaded
from disk by pressing [L]. the program will automatically determine whereabouts
in memory the file should reside, even if the file has never been loaded into
PS.CLIP.ART before. If the file is not a multiple of 576 bytes long, it will not
be loaded. Note that loading a clip art file destroys any already in memory,
although the minipic buffer remains unchanged.

Edit Menu options
=================

As well as handling clipping of graphics from the hires screen, the edit screen
allows some other functions as well. Graphics in the minipic buffer can be
x-drawn to the screen in one of three sizes by pressing [X]. A flashing
rectangle indicates the draw area. It is moved in the same way as the capyure
rectangle. [esc] exits or [return] draws. The hires screen may be mirrored
horizontally by pressing [M] or flipped vertically by pressing [F] or inverted
by pressing [I]. The machine language routines that carry out these functions
reside in the file "CLIP.ART.CODE". The Merlin Pro source code is included if
you wish to use these routines in your own programs.

Using graphics in your own programs
===================================

This ability is one of the most useful things about PS.CLIP.ART. Three different
drawing programs are included in the package. They can be called from BASIC or
assembly.

MG.UNPACK This routine unpacks a standard 88 x 52 mini graphic from a clip-art
file created with PS.Clip.Art into the current hires drawing page.

Load: into any free page of memory (relocatable) Length is $100

Graphics: drawn from clip art file, located at appropriate mem. location

Scales: draws at scale = 1, 2 or 3

Entry: desired X,Y coordinates of the top left of the graphic should be stored
in HORIZ ($E0 = 224) and VERT ($E2 = 226). The desired scale factor stored (1,2
or 3) stored in SCALE ($E7 = 231) or set with the Applesoft SCALE= command. To
draw one pic by number either JSR LoadAdr with picnum in A, or CALL LoadAdr+2 or
JSR LoadAdr+2 with picnum in 215 ($D7). To draw next picture in succession
either CALL LoadAdr+52 or JSR LoadAdr+$34

Execution time: Scale = 1 takes ~270 milliseconds, Scale=2 takes ~430 ms,
Scale=3 takes ~610 ms.

UNPACK.FAST This routine operates in almost exactly the same manner as MG.UNPACK
except the only acceptable value for scale=1. It does it fast, hence its name.

Load: into any free page of memory (relocatable) Length is $9A

Graphics: drawn from clip art file, located at appropriate mem. location

Scales: draws only at scale = 1

Entry: desired X,Y coordinates of the top left of the graphic should be stored
in HORIZ ($E0 = 224) and VERT ($E2 = 226) and desired picnum should be stored in
PICNUM ($D7=215). Entry is then JSR LoadAdr+6 or CALL LoadAdr+6 from BASIC.
Alternately picnum can be passed in A with JSR LoadAdr+4 or picnum passed in A,
and x,y, coords passed in X,Y with JSR LoadAdr. To draw the next graphic in the
file use JSR LoadAdr+$27 or CALL LoadAdr+39

Execution Time: ~143 milliseconds.

UPK.OBJ This routine unpacks 572 bytes of graphic data from a specified memory
location, not a clip art file. Its opartion is almost the same as MG.UNPACK

Load: loads at $300, length is $D0 bytes

Graphics: Draws from 572 bytes of graphic data in memory. The memory locations
of the graphic data are by default from $9621 to $9860, but different locations
can be set by storing different values at the start of the program, the low byte
at $301 (769) and the high byte at $305 (773).

Scales: Draws at scale = 1, 2 or 3

Entry: Store HORIZ, VERT, SCALE as for MG.UNPACK. The routine is called by CALL
768 from applesoft or JSR $300 from assembly.

For all the drawers, acceptable ranges for HORIZ and VERT are:

Scale = 1, Horiz = 0 to 192, Vert = 0 to 140
        2          0 to 104         0 to 88
        3          0 to 16          0 to 36

(The other program used by PS.CLIP.ART, AUX.TYPE.SET is called to set the
auxiliary type of a 605 byte graphic so that NPS will recognise it. It also
handles the determining of the load address of clip art files)

Use and enjoy! 
==============

This is the first of several programs that I am releasing to the public domain.
Keep an eye open for more Philip Lamb Digital Dynamics software. I hope you make
use of this program, and I also encourage you to buy Broderbund Software's New
Print Shop software. It is a great package, and a substantial improvement over
the old one.

